8. Quake-C Built-in functions

These are the built-in functions of Quake C. Since they are hard-coded in C, they cannot be redefined, but they are very fast.

8.1 Math functions

Function: anglemod

float anglemod (float angle)
returns angle in degree, module 360.

Function: rint

 
 float rint(float val)
Returns val, rounded up to the closest integer value.

Function: floor

 
 float floor(float val)
Returns val, rounded up to the integer below (like the equivalent function in C).

Function: ceil

 
 float ceil(float val)
Returns val, rounded up to the integer above (like the equivalent function in C).

Function: fabs

 
 float fabs(float val)
Returns absolute value of val (like the equivalent function in C).

Function: random

Returns a random floating point number between 0.0 and 1.0.

Function: ftos

string ftos(float value)
Float to string: converts value to string.

8.2 Vector maths

Function: normalize

vector normalize(vector v)
   returns a vector of length 1
Gives the vector colinear to v, but of length 1. This can be useful for calculation of distance along an axis.

Function: vlen

float vlen(vector v)
Returns the length of vector v (never < 0).

Function: vectoyaw

float vectoyaw(vector v)
   returns and angle in degree
Vector to yaw: calculates the yaw angle (bearing) corresponding to a given 3D direction v.

Function: vectoangles

vector vectoangles(vector v)
   returns vector 'pitch  yaw  0 '
Vector to angles: calculates the pitch angle (aiming) and yaw angle (bearing) corresponding to a given 3D direction v.

Function: vtos

string vtos(vector v)
Vector to String: print a vector, as a string.

Function: makevectors

void makevectors(vector angles)
  angle = 'pitch yaw 0'
Calculate the vectors pointing forward, right and up, according to the provided angles.
Returns result in the global variables: 
	
vector	v_forward;  // points forward
vector  v_up;       // points up
vector  v_right;    // points toward the right

8.3 Sounds

Function: sound

void sound (entity source, float channel, string sample, float volume, float attenuation)
  source = entity emiting the sound (ex: self)
  channel = channel to use for sound 
  sample = name of the sample WAV file (ex: "ogre/ogdrag.wav")
  volume = 0.0 for low volume, 1.0 for maximum volume
  attenuation= attenuation of sound
The entity emits a sound, on one of it's 8 channels.

Function: ambientsound

void ambientsound(vector position, string sample, float volume, float attenuation)
  position = position, in 3D space, inside the level
  sample = name of the sample WAV file (ex: "ogre/ogdrag.wav")
  volume = 0.0 for low volume, 1.0 for maximum volume
  attenuation= attenuation of sound
An ambient sound is emited, from the given position.

8.4 Entity management

Function: spawn

entity spawn ()
       returns an empty entity.
Create a new entity, totally empty. You can manually set every field, or just set the origin and call one of the existing entity setup functions.

Function: remove

void remove (entity e)
Removes entity e from the world (R.I.P.).

Function: makestatic

void makestatic (entity e)
Make an entity static to the world, by sending a broadcast message to the network.
The entity is then removed from the list of dynamic entities in the world, and it cannot be deleted (until the level ends).

Function: nextent

entity nextent(entity e)
Returns entity that is just after e in the entity list.
Useful to browse the list of entities, because it skips the undefined ones.

Function: find

entity find (entity start, .string field, string match)
	start = begining of list to search (world, for the begining of list)
	field = entity field that must be examined (ex: targetname)
	match = value that must be matched (ex: other.target)
	returns the entity found, or world if no entity was found.
Searches the server entity list beginning at start, looking for an entity that has entity.field = match.

Example: find the first player entity 

 e = find( world, classname, "player");
Take care that field is a name of an entity field, without dot, and without quotes.

Function: findradius

entity findradius (vector origin, float radius)
        origin = origin of sphere
        radius = radius of sphere
Returns a chain of entities that have their origins within a spherical area.
The entity returned is e, and the next in the chain is e.chain, until e==FALSE.
Typical usage: find and harm the victims of an explosion. 
  e = findradius( origin, radius)
  while(e)
  {
    T_Damage(e, ... ) // Let God sort his ones!
    e = e.chain
  }

Function: setmodel

void setmodel (entity e, string model)
  e = entity whose model is to be set
  model = name of the model (ex: "progs/soldier.mdl")
Changes the model associated to an entity. This model should also be declared by precache_model. Please set e.movetype and e.solid first.

Function: lightstyle

void lightstyle(float style, string value)
        style = index of the light style, from 0 to 63.
        value = (ex: "abcdefghijklmlkjihgfedcb")
Modifies a given light style. The light style is used to create cyclic lighting effects, like torches or teleporter lighting.
There are 64 light styles, from 0 to 63. If style is not strictly comprised in these values, the game may crash.
styles 32-62 are assigned by the light program for switchable lights.
value is a set of characters, whose ascii value indicates a light level, from "a" (0) to "z" (30).

8.5 Entity movements

Function: ChangeYaw

void ChangeYaw()
Change the horizontal orientation of self. Turns towards self.ideal_yaw at self.yaw_speed, and sets the global variable current_yaw.
Called every 0.1 sec by monsters

Function: walkmove

float walkmove(float yaw, float dist)
       returns TRUE or FALSE
Moves self in the given direction.
Returns FALSE if could not move (used to detect blocked monsters).

Function: droptofloor

float droptofloor()
       returns TRUE or FALSE
Drops self to the floor, if the floor is less than -256 coordinates below.
Returns TRUE if landed on floor.
Mainly used to spawn items or walking monsters on the floor.

Function: setorigin

void setorigin (entity e, vector position)
  e = entity to be moved
  position = new position for the entity
Move an entity to a given location. That function is to be used when spawning an entity or when teleporting it.
This is the only valid way to move an object without using the physics of the world (setting velocity and waiting).
DO NOT change directly e.origin, otherwise internal links would be screwed, and entity clipping would be messed up.

Function: setsize

void setsize (entity e, vector min, vector max)
  e = entity whose bounding box is to be set  
  min = minimum, for bounding box (ex: VEC_HULL2_MIN)
  max = maximum, for bounding box (ex: VEC_HULL2_MAX)
Set the size of the entity bounding box, relative to the entity origin. The size box is rotated by the current angle.

Function: movetogoal

void movetogoal (float step)
Move self toward it's goal.
Used for monsters.

8.6 Fighting

Function: aim

vector aim(entity e, float missilespeed)
Returns a vector along which the entity e can shoot.
Usually, e is a player, and the vector returned is calculated by auto-aiming to the closest enemy entity.

Function: particle

void particle(vector origin, vector dir, float color, float count)
    origin = initial position
    dir = initial direction
    color = color index (73,75, 
    count = time to live, in seconds
Create a particle effect (small dot that flies away). 
color = 0   for chunk
color = 75  for yellow
color = 73  for blood red
color = 225 for entity damage

Function: checkclient

entity checkclient()
Returns client (or object that has a client enemy) that would be a valid target.
If there are more than one valid options, they are cycled each frame.
If (self.origin + self.viewofs) is not in the PVS of the target, 0 (false) is returned.

8.7 Collision checking

Function: traceline

traceline (vector v1, vector v2, float nomonsters, entity forent)
  v1= start of line
  v2= end of line
  nomonster= if TRUE, then see through other monsters, else FALSE.
  forent= ignore this entity, it's owner, and it's owned entities.
    if forent = world, then ignore no entity.
Trace a line of sight, possibly ignoring monsters, and possibly ignoring the entity forent (usually, forent = self).
This function is used very often, tracing and shot targeting.
Traces are blocked by bounding boxes and exact bsp entities.
Returns the results in the global variables: 
float trace_allsolid;
  // never used
float trace_startsolid;
  // never used
float trace_fraction;
  // fraction (percent) of the line that was traced, before
  // an obstacle was hit. Equal to 1 if no obstacle were found.
vector trace_endpos; 
  // point where line ended or met an obstacle.
vector trace_plane_normal;
  // direction vector of trace (?)
float  trace_plane_dist;  
  // distance to impact along direction vector (?)
entity trace_ent;      
  // entity hit by the line
float  trace_inopen;
  // boolean, true if line went through non-water area.
float  trace_inwater;
  // boolean, true if line went through water area.

Function: checkpos

CURRENTLY DISABLED. DO NOT USE. 
scalar checkpos (entity e, vector position)
Returns true if the given entity can move to the given position from it's current position by walking or rolling.

Function: checkbottom

float checkbottom(entity e)
       e = entity that is to be checked
       return TRUE or FALSE
Returns TRUE if on the ground.
Used only for jumping monster, that need to jump randomly not to get hung up (or whatever it actually means).

Function: pointcontents

float pointcontents(vector pos)
Returns the contents of the area situated at position pos.
Used to know if an area is in water, in slime or in lava.
Makes use of the BSP tree, and is supposed to be very fast.

8.8 Server managment

Function: changelevel

void changelevel (string mapname)
Warp to the game map named mapname. Actually executes the console command "changelevel" + mapname, so if you want to alias it...

Function: setspawnparms

void setspawnparms (entity client)
Restore the original spawn parameters of a client entity.
Doesn't work if client is not a player.

Function: stuffcmd

stuffcmd (entity client, string text)
       client = player that is to receive the command
       text = text of the command, ended by \n (newline).
Send a command to a given player, as if it had been typed on the player's console.

Don't forget the \n (newline) at the end, otherwise your command will not be executed, and will stand still on the console window.

Examples: 

   stuffcmd(self, "bf\n");         // create a flash of light on the screen
   stuffcmd(self, "name Buddy\n"); // name the player Buddy

Mostly used to send the command bf, that creates a flash of light on the client's screen.

8.9 Print messages

Function: bprint

void bprint (string text)
	text = text of the message
Broadcast a message to all players on the current server.

Function: centerprint

void centerprint( entity client, string text)
	client = player that is to receive the message
	text = text of the message
Sends a message to a specific player, and print it centered.

Function: sprint

void sprint (entity client, string text)
        client = player that is to receive the message
	text = text of the message
Sends a message to a player.

8.10 Console

Function: localcmd

void localcmd (string text)
       text = text of the command, ended by \n (newline).
Execute a command on the server, as if it had been typed on the server's console.

Examples: 

   localcmd("restart\n");      // restart the level
   localcmd("teamplay 1\n");   // set deathmatch mode to teamplay
   localcmd("killserver\n");   // poor server...

Function: dprint

void dprint (string text)
	text = text of the message
Prints a message to the server console.

Function: cvar

float cvar (string variable)
      variable = see console variables
returns the value of a console variable.

Function: cvar_set

float cvar_set (string variable, string value)
      variable = see console variables
sets the value of a console variable.

8.11 Debugging

Function: eprint

void eprint (entity e)
	e = entity to print
Print details about a given entity (for debug purposes).

Function: coredump

void coredump()
Print all entities

Function: traceon

void traceon()
Start tracing functions, end them with traceoff()

Function: traceoff

void traceoff()
End traces started by traceon()

Function: break

void break()
Exit the programs. Never used?

Function: error

void error (string text)
Print an error message.

Function: objerror

void objerror (string text)
Print an error message related to object self.

8.12 Precaching files

Those functions are used to declare models, sounds and stuff, before the PAK file is built.

Just follow this rule: whenever one of your functions makes use of a file that's not defined in Quake, precache this file in a function that will be called by worldspawn().

Then, the QCC compiler can automatically include in the PAK file all the files that you really need to run your programs.

And when the level starts running, those precache orders will be executed, so as to attribute a fixed table index to all those files.

DO NOT USE those functions in code that will be called after worldspawn() was called. As a matter of fact, that could bomb Quake (restarting the level, without crashing the game).

Files can only be precached in spawn functions.

Function: precache_file

void precache_file(string file)
  file = name of the file to include in PAK file.
Does nothing during game play.
Use precache_file2 for registered Quake.

Function: precache_model

void precache_model(string file)
  file = name of the MDL or BSP file to include in PAK file.
Does nothing during game play.
Must be used in a model's spawn function, to declare the model file.
Use precache_model2 for registered Quake.

Function: precache_sound

void precache_sound(string file)
  file = name of the WAV file to include in PAK file.
Does nothing during game play.
Must be used in a model's spawn function, to declare the sound files.
Use precache_sound2 for registered Quake.